home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / prbgi097.zip / PRINTBGI.DOC < prev    next >
Text File  |  1992-12-15  |  14KB  |  280 lines
  1. #define C_only
  2. #define Pascal_only
  3.  
  4. Documentation of PRINTBGI package v0.97 (C) Andrzej Resztak 1991,1992,
  5. all rights reserved.
  6.  
  7. To contact the author write to
  8.  
  9.    Andrzej Resztak
  10.    ul. K. Wallenroda 2c/18
  11.    20-607 Lublin
  12.    POLAND
  13.  
  14. or (preferably) to e-mail address:
  15.    Resztak@PLUMCS11.bitnet
  16.  
  17.                         Introduction
  18.                         ============
  19.  
  20.    This is the version 0.97 of my PrintBGI toolkit. It was developed to
  21. help programmers using Borland languages (Borland/Turbo C(++)
  22. or Turbo Pascal) and BGI drivers to print graphics on the printer
  23. (and in the future on the other devices) as easy as you can draw it
  24. on the screen. In fact even more, the same function can produce
  25. it's output on a screen or on a printer according to conditions
  26. at which it was called.
  27.    It's really easy to learn. Developing your own applications does
  28. not require writing two similar procedures (one for screen drawing
  29. and the other for printer or plotter).
  30. Maintenance of the code is simple, since all extensions or bug fixes
  31. must be made in one place only. I hope you will enjoy this package.
  32.  
  33.    For registration, license and payment see REGISTER.DOC.
  34.    #if kkkkk
  35.    For examples description see EXAMPLE.DOC.
  36.    #endif
  37.  
  38. This file contains all technical news you must understand to use
  39. this package easy and effectively.
  40.  
  41.  
  42.    It is quite possibly that this program may not work on your
  43. printer. For example I have never tested it on original IBM printer.
  44. Of course it was tested on some compatible printers but I cannot be
  45. quite sure which command is "compatible" and which is an enhancement.
  46. So please, let me know if this program does not work with your printer.
  47. My address is given at the end of this file.
  48.  
  49.  
  50.             SOME OVERVIEW
  51.             ==============
  52.  
  53.    This package can be divided into two independent parts. First is
  54. BGI driver called by me BItImage BGI driver. This driver can be used
  55. to create bit maps of any size of any picture. Note however that
  56. the BGI driver does only some low level work (hardware specific) and
  57. in most cases it depends on high level routines contained in Borland
  58. graphics library kernel. Since there are some differences between printer
  59. and screen oriented devices the initialization of my BitImage BGI
  60. driver is somewhat different of initialization of standard Borland
  61. video BGI drivers. For example it cannot perform any auto detection;
  62. specifying printer being used does not determine the size of the graphic
  63. output and there is some more minor differences. Because of these
  64. differences you must call some PRT_Setxxxxxxx functions of the package to
  65. specify parameters at which you want the BitImage driver to work. And
  66. initialization of the driver should be done using PRT_initgraph function
  67. instead of standard initgraph routine.
  68.    The second part of the package make routines contained in PRTGRAPH library
  69. which hide some of the differences between my BitImage driver and
  70. standard Borland video drivers. They also will make it very easy to print
  71. something on your output device (currently only the dot matrix printers).
  72.  
  73.  
  74.    Now I describe you the easiest way you can add graphic output
  75. to your programs using this PRINTBGI toolkit. Other sections
  76. will let you know some more features, but this section is very good
  77. for beginning, I hope.
  78.  
  79.    #if   C_only
  80.    For C users.
  81.  
  82.    First, I highly recommend you to include prototypes of all functions
  83. defined in PRINTBGI package by just inserting
  84. #include <PRTGRAPH.H>
  85. statement at  the  beginning  of  your  module.  Although  it  is  not
  86. necessary I also recommend you to place PRTGRAPH module after any standard
  87. modules you use. It'll enable me some tricky modifications in the future
  88. versions of this package.
  89.    You must also remember about linking in PRTGRAPH.LIB either
  90. listing it in PRJ file in integrated environment or adding at the
  91. command line invoking stand alone version of the compiler (or linker).
  92.    #endif   C_only
  93.  
  94.    #if   Pascal_only
  95.    For Pascal users.
  96.  
  97.    You must list PRTGRAPH unit (among other units you are using) in the
  98. uses clause. You may also list PDrivers unit if you want to use symbolic
  99. constants defined in it.
  100.    Although it is not necessary I recommend you to place PRTGRAPH
  101. module after any standard modules you use. It'll enable me some tricky
  102. modifications in the future versions of this package.
  103.    #endif   Pascal_only
  104.  
  105.  
  106.    Next I assume that you like modular structure programming and have
  107.    routine called (say) DrawFunc which meets following conditions.
  108.       - It draws on the screen the picture you want to print it out.
  109.       - It does not use any nonstandard procedures (that is not
  110.         defined in GRAPH.TPU or GRAPHICS.LIB) to manipulate screen
  111.         output.
  112.       - It does not use initgraph,restorecrtmode,closegraph or setgraphmode
  113.         function. It simply assumes that appropriate graphic mode was
  114.         established before calling it and will be close down after
  115.         it finishes.
  116.       - It is written in BGI independent way. That is it uses getmaxx,
  117.         getmaxy, getmaxcolor, getaspectratio to get device dependent
  118.         characteristic and scales all output according to it.
  119.       - If you are using my recommended way to print your picture out, that
  120.         is you are using PRT_PrintBGI function then it may happen that this
  121.         function will call your drawing routine few or several times to print
  122.         out the whole picture. This may happen when there is not enough free
  123.         memory to build the whole bit image map of the picture at once. In
  124.         that case the bit map will be created piece by piece (each time
  125.         calling your drawing routine).
  126.         So, although it is not necessary it is recommended that your routine
  127.         will draw the same picture (pixel in pixel) each time it will be
  128.         called by PRT_PrintBGI function. Of course in the next invoke
  129.         of the PRT_PrintBGI routine your DrawFunc may draw something
  130.         completely different.
  131.       - It is declared as huge function if you are using C compiler.
  132.  
  133.       ( If it is not your case (you don't have such a function)  you may
  134.         either rewrite your code to have such a function or use some lower
  135.         level functions included in this package. I once again highly
  136.         recommend you to choose the first method. )
  137.  
  138.       If you have such a function you must inform the package what kind
  139.    of printer you have and at what resolution you want it to operate.
  140.    To do that just call PRT_SetPrinterDrv function with appropriate parameters
  141.    PrinterNo and ModeNo (use constants defined in PRTGRAPH.H or in
  142.    PRTGRAPH.PAS) and PRT_SetPicture to define size and other picture options.
  143.    For example the following statements may print out picture drawn by
  144.    DrawFunc on the IBM ProPrinter.
  145.  
  146.    #if C_only
  147.    {  /* C version */
  148.       int   PRTdrv,PRTmode,ReturnCode;
  149.       PRT_LinkDrivers(); /* link drivers definitions into an executable code 
  150. */
  151.       PRT_SetPrinterDrv ( IBM9, IBM9_120x72 );
  152.       PRT_SetPicture ( 4000,3000, PRT_INVERSE );
  153.       PRTdrv = DETECT;
  154.       PRTmode=0;
  155.       /* If you want you may linked in the BitImage BGI driver into the */
  156.       /* EXE file. To do so remove comment markers from the following two lines. */
  157.       /* PRTdrv = PRT_installuserdriver ( "BitImage", NULL );  */
  158.       /* PRT_registerfarbgidriver ( BitImage );               */
  159.       ReturnCode = PRT_PrintBGI ( &PRTdrv,&PRTmode,"d:\\bc\\bgi",
  160.                                   DrawFunc, NULL );
  161.    }
  162.    #endif
  163.  
  164.    #if Pascal_only
  165.    (* Pascal version *)
  166.    var PRTdrv,PRTmode,ReturnCode : integer;
  167.    Begin
  168.       rc:=PRT_LinkDrivers; { link drivers definitions into an executable code 
  169. }
  170.       PRT_SetPrinterDrv ( IBM9, IBM9_120x72 );
  171.       PRT_SetPicture ( 4000,3000, PRT_INVERSE );
  172.       { rc := PRT_SetOutName('file.tst'); }
  173.       PRTdrv := DETECT;
  174.       PRTmode := 0;
  175.       (* If you want you may linked in the BitImage BGI driver into the *)
  176.       /* EXE file. To do so remove comment markers from the following two lines. */
  177.            { PRTdrv := PRT_installuserdriver ( 'BitImage', NIL ); }
  178.            { rc := PRT_registerbgidriver ( @BitImage ); }
  179.            rc := PRT_PrintBGI ( PRTdrv,PRTmode,'d:\tp\bgi', Draw, nil );
  180.    End;
  181.    #endif
  182.  
  183.    In the best case it's all you have to do. Isn't it easy? I'm sure you
  184. must admit it is.
  185.  
  186.    Of course in most situations it is not enough. Above statements
  187. will cause all output to be sent to the standard PRN device.
  188. If you would like (or have to cause you don't have the printer at
  189. LPT1 for example) to change these parameters you
  190. should call some more functions of the PRINTBGI package as well
  191. as you should code some lines to let user of your program specify
  192. his own requirements. But all of this can be done!
  193.    You may also wish to print in inverse, reverse, with any density
  194. at any size. The only disadvantage of using this package is that it
  195. is perceptible slower than usual Print Screen procedures.
  196.  
  197.  
  198.  
  199.                       ===============
  200.                       SCREEN  PREVIEW
  201.                       ===============
  202.  
  203.    Starting with version 0.97 I've added screen preview option to my PrintBGI
  204. package. It enables you to display at the screen buffer contents just
  205. before printing. To do that you must register your own printing function
  206. using PRT_SetUserPrintFunc function. An example of such routine is given
  207. in both C and Pascal (see UserPRTF.C or UserUnit.pas file) and is used
  208. in BGIDEMO example programs. These functions use some PrintBGI internal
  209. functions to display buffer contents on the screen. I hope that they
  210. are so simple than no more comments are needed.
  211.  
  212.    In the way this feature is used in BGIDEMO examples it does not
  213. give you full WYSIWYG. This is because different aspect ratio for the
  214. screen and printer being used. So what will be printed on the printer
  215. as the circle may be seen on the screen as an ellipse of different
  216. radiuses. If you want full WYSIWYG you must build picture twice.
  217. Once to let user see it and if he (or she) decides to print it out, build it
  218. once again and print (this time without displaying it on the screen).
  219. On the very fast computers this solution may be acceptable.
  220.    Note also that on black & white monitors you will not see color
  221. pictures. To enable fast scrolling all high order bits are just ignored.
  222. So you will see on the b&w screen odd colors only (as white) and all
  223. even colors you will see as black.
  224.  
  225.    In current release screen preview option will work only with the
  226. following Borland's drivers EGA, EGA64, EGAMONO, HERC, VGA and CGA
  227. in CGAHI(640x200 2 color) mode. It will not work with other Borland
  228. supplied drivers and is likely to fail with most other vendors supplied
  229. BGI drivers. It is your responsibility to ensure that you are using
  230. one of compatible drivers, otherwise results are unpredictable.
  231.  
  232.    Note that screen preview option may be not compatible with some future
  233. printers drivers (e.g. Postscript driver is the first one candidate to not
  234. allow screen preview option). This does not necessarily mean that some
  235. drivers will not allow screen preview option to work, but that there is such
  236. possibility that screen preview will not always be available. Thus
  237. there is a function (called PRT_ScreenPreviewPossible) returning
  238. nonzero (true) if screen preview option is available. Both examples
  239. of user defined print function use it to ensure the proper work of buffer
  240. display functions.
  241.  
  242.  
  243.                         ==============
  244.                         MULTIPLE BGI's
  245.                         ==============
  246.  
  247.    It seems that Borland designing BGI drivers thought only a little
  248. about support of different graphic devices or few of them active
  249. at the same time. In the documentation I have, BGI drivers have a field
  250. (Device Type Identifier) value zero of which defines them as screen
  251. driver, I believe. And in few places in the documentation there are
  252. sentences about BGI drivers for printers or plotters. However I found
  253. it impossible to have two or more BGI drivers active at the same time.
  254. If it is quite possible that I am wrong it seems that you can use
  255. initgraph function only if previously active BGI driver is closed
  256. (using closegraph function). It makes it impossible to have screen in graphic
  257. mode (screen BGI active) and print picture using printer BGI driver
  258. at the same time. You cannot also use two graphic displays (IBM can
  259. have two video adapters). Since Some users didn't like switching to text
  260. mode during printing graphic I decided to do something to avoid this
  261. problem. It was not easy and unfortunately I used some tricks which
  262. may not work with future versions of BGI drivers (if there will be any).
  263.    Thus I developed small "pseudo" BGI driver and called it INTERBGI.
  264. It is "pseudo" BGI driver because it does not perform any function
  265. itself but calls real BGI driver to do real things. Using such interface
  266. between Borland graphic kernel and BGI drivers enables me to switching
  267. between them. In fact it's not so easy but we can stay with it.
  268.    Support for multiple BGI drivers allows you to initialize one BGI
  269. driver without closing down the previously active one. The previously
  270. active BGI driver stays in suspended mode and restores control
  271.  
  272.  
  273.    To see complete description of all functions available see
  274. file FUNCTION.DOC.
  275.  
  276.  
  277.    /* end of PRINTBGI.DOC  */
  278.  
  279.  
  280.